ENG-1590 Migrate existing docs content into Nextra content directories#930
ENG-1590 Migrate existing docs content into Nextra content directories#930
Conversation
- Introduced a new `docsRouteMap.ts` file to manage documentation sections and redirects for Roam and Obsidian platforms. - Updated `next.config.ts` to include dynamic redirects based on the new route map. - Refactored the layout components for documentation pages to utilize a consistent theme layout. - Removed outdated `page.tsx` files for Roam and Obsidian, replacing them with new landing pages that leverage Nextra for content rendering. - Added new metadata and content files for various documentation sections, enhancing the overall documentation structure and accessibility.
|
This pull request has been ignored for the connected project Preview Branches by Supabase. |
…ndexing script - Modified ESLint configuration to include new file patterns and global variables. - Updated package.json to change the postbuild script to a new documentation indexing script. - Added a new script for building a search index from documentation markdown files. - Introduced tests for the new indexing script to ensure correct functionality.
- Replaced the Image component with a span that utilizes an SVG mask for the logo rendering. - Added a new SVG file for the logo to enhance scalability and styling flexibility.
- Introduced a new `.nextra-reset` class in `nextra-css.css` to set the content width to 90rem, enhancing layout consistency across the website.
- Introduced a new `DocsPageTemplate` component to standardize the layout for documentation pages. - Updated the Obsidian and Roam documentation page files to utilize the new `DocsPageTemplate`, improving code consistency and maintainability. - Removed direct usage of `useMDXComponents` in favor of the new template for better structure.
…ncing clarity in node and relation descriptions - Removed the "Overview" section from multiple documentation files to streamline content. - Improved formatting and clarity in the node and relation documentation across various files. - Ensured consistency in the presentation of tag rules and examples in the node-tags documentation.
- Renamed "Relations and patterns" to "Legacy relations patterns" for clarity. - Removed outdated sections and improved links to the new stored relations documentation. - Added new files for grammar components, including base grammar, nodes, and operators-relations. - Introduced a migration guide for transitioning to stored relations, enhancing user experience and clarity.
- Added new custom redirects for Roam documentation to improve navigation. - Simplified the fundamentals section by removing outdated entries. - Introduced a utility function for creating redirects, enhancing code maintainability.
…elated documentation for clarity. The "Installation from Roam Depot" entry has been deleted, and the main installation page has been revised for improved readability.
- Removed unnecessary sections and improved formatting across multiple files. - Standardized headings and titles for better readability. - Updated related links and streamlined content to enhance user navigation.
- Replaced Next.js Link components with anchor tags for hard navigation to prevent CSS conflicts between marketing and documentation sections. - Updated global styles to apply marketing-specific styles, enhancing the overall design consistency across the site. - Removed unused CSS variables related to theming for a cleaner stylesheet.
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
- Updated CSS to ensure search result links and highlighted text have consistent color in light mode. - Applied !important to maintain visibility against the background.
Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>
|
@coderabbitai full review |
✅ Actions performedFull review triggered. |
| @@ -0,0 +1,148 @@ | |||
| export const ROAM_DOC_SECTIONS = { | |||
| welcome: ["getting-started", "installation", "installation-roam-depot"], | |||
There was a problem hiding this comment.
🟡 Redirect generated for non-existent installation-roam-depot destination page
The ROAM_DOC_SECTIONS.welcome array at docsRouteMap.ts:2 includes "installation-roam-depot", which causes buildPlatformRedirects to generate a redirect from /docs/roam/installation-roam-depot → /docs/roam/welcome/installation-roam-depot. However, there is no content file at content/roam/welcome/installation-roam-depot.md (the old page was removed in commit 311123d), and the content/roam/welcome/_meta.ts does not list it either. This means users visiting the old URL will be permanently redirected (301) to a page that returns a 404, which is worse than simply 404-ing on the original URL since browsers and search engines cache permanent redirects.
| welcome: ["getting-started", "installation", "installation-roam-depot"], | |
| welcome: ["getting-started", "installation"], |
Was this helpful? React with 👍 or 👎 to provide feedback.
📝 WalkthroughWalkthroughThis PR comprehensively migrates the website's documentation system from a custom layout to Nextra, a Next.js documentation framework. It replaces old docs routing with dynamic Nextra-based routes for both Roam and Obsidian, adds extensive organized documentation content across both platforms, introduces custom layout and theme components, updates the Logo component for flexibility, implements custom search indexing, scopes global styling, and restructures the homepage navigation to integrate with the new documentation structure. Changes
Sequence Diagram(s)No sequence diagrams generated. The changes are primarily content additions, routing restructuring, and component creation without complex multi-component interactions that would benefit from visualization. Estimated code review effort🎯 4 (Complex) | ⏱️ ~70 minutes Possibly related PRs
Suggested labels
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 10
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
🟡 Minor comments (27)
apps/website/content/obsidian/use-cases/_meta.ts-6-6 (1)
6-6:⚠️ Potential issue | 🟡 MinorAlign nav label with the page title for this slug.
Line [6] maps
research-roadmappingto “Research notes”, but the page title is “Research roadmapping”. This mismatch can confuse users in navigation.Suggested fix
- "research-roadmapping": "Research notes", + "research-roadmapping": "Research roadmapping",🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/obsidian/use-cases/_meta.ts` at line 6, The nav label for the slug "research-roadmapping" currently maps to "Research notes" which doesn't match the page title "Research roadmapping"; update the mapping value for the "research-roadmapping" key in _meta.ts from "Research notes" to "Research roadmapping" so the nav label aligns exactly with the page title.apps/website/content/roam/fundamentals/what-is-a-discourse-graph.md-1-6 (1)
1-6:⚠️ Potential issue | 🟡 MinorTitle missing question mark - inconsistent with navigation label.
The frontmatter title "What is a discourse graph" should include a question mark to match the expected navigation label "What is a discourse graph?" defined in
_meta.ts.Suggested fix
--- -title: "What is a discourse graph" +title: "What is a discourse graph?" date: "2025-01-01" author: "" published: true ---🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/fundamentals/what-is-a-discourse-graph.md` around lines 1 - 6, The frontmatter title in the markdown (the "title" field in apps/website/content/roam/fundamentals/what-is-a-discourse-graph.md) is missing a question mark and should match the navigation label; update the frontmatter "title" value from "What is a discourse graph" to "What is a discourse graph?" so it exactly matches the expected label defined in _meta.ts (ensure only the title string is changed).apps/website/content/roam/use-cases/reading-clubs.md-5-8 (1)
5-8:⚠️ Potential issue | 🟡 MinorDon’t publish this page until content is ready.
Line [8] is placeholder text while Line [5] is
published: true. Please either add substantive content now or keep it unpublished.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/use-cases/reading-clubs.md` around lines 5 - 8, The page is published but contains only placeholder text ("Description coming soon!"); either replace the placeholder with substantive content for this use-case or change the front-matter flag published: true to published: false to keep it unpublished until complete—update the string "published: true" or the placeholder line accordingly in apps/website/content/roam/use-cases/reading-clubs.md.apps/website/content/roam/fundamentals/grammar/index.md-2-15 (1)
2-15:⚠️ Potential issue | 🟡 MinorTighten page structure to avoid navigation ambiguity.
This page currently repeats the
Nodeslink (Lines [8] and [15]) and mixes “Extension grammar” with “Relation grammar building blocks.” Please deduplicate the link and align title/heading scope.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/fundamentals/grammar/index.md` around lines 2 - 15, The page duplicates the "Nodes" link and mixes scopes between the frontmatter title "Extension grammar" and the section heading "## Relation grammar building blocks"; remove the duplicate "Nodes" entry so it appears only once in the bullet list and make the heading match the page title's scope (either rename "## Relation grammar building blocks" to "## Extension grammar building blocks" or change the frontmatter title to "Relation grammar") so the page has a single clear scope; update the remaining links accordingly to keep navigation correct.apps/website/content/roam/use-cases/research-roadmapping.md-5-8 (1)
5-8:⚠️ Potential issue | 🟡 MinorAvoid publishing placeholder-only docs pages.
Line [5] marks this page as published, but Line [8] is still placeholder copy. This will surface incomplete content in navigation/search. Consider setting
published: falseuntil real content is added.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/use-cases/research-roadmapping.md` around lines 5 - 8, The frontmatter flag published: true is exposing a placeholder page ("Description coming soon!")—change the frontmatter value to published: false until substantive content replaces the placeholder, or replace the placeholder text with real content and keep published: true; locate the published frontmatter entry and the placeholder body in the same file (roam/use-cases/research-roadmapping.md) and update either the frontmatter or the page content accordingly to prevent incomplete pages from appearing in navigation/search.apps/website/content/roam/use-cases/reading-clubs.md-10-10 (1)
10-10:⚠️ Potential issue | 🟡 MinorUse lowercase for generic term in docs copy.
At Line [10], “Reading Club” should be “reading club” (unless it is an exact product/UI title).
As per coding guidelines, “Use sentence case for documentation copy by default... keep generic feature terms lowercase.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/use-cases/reading-clubs.md` at line 10, The link text "Get in touch (mailto:joechan@umd.edu) if you're interested in joining a Reading Club!" uses a capitalized generic term; update the string in the document so "Reading Club" becomes "reading club" to follow sentence case (unless it is an exact product/UI name), and scan the same file for other occurrences of "Reading Club" to normalize them consistently.apps/website/content/roam/guides/_meta.ts-1-4 (1)
1-4:⚠️ Potential issue | 🟡 MinorRename constant to uppercase to match repository naming rules.
metais declared as a constant at Line [4]; per repo convention, constants should use UPPERCASE.♻️ Proposed fix
-/* eslint-disable `@typescript-eslint/naming-convention` */ +/* eslint-disable `@typescript-eslint/naming-convention` -- slug keys are intentionally kebab-case */ import type { MetaRecord } from "nextra"; -const meta: MetaRecord = { +const META: MetaRecord = { "creating-discourse-nodes": "Creating nodes", "tagging-candidate-nodes": "Tagging candidate nodes", "creating-discourse-relationships": "Creating relationships", "migration-to-stored-relations": "Migration to stored relations", "exploring-discourse-graph": "Exploring your discourse graph", "querying-discourse-graph": "Querying", "extending-personalizing-graph": "Extending", "sharing-discourse-graph": "Sharing", }; -export default meta; +export default META;As per coding guidelines, “Use UPPERCASE for constants.”
Also applies to: 15-15
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/guides/_meta.ts` around lines 1 - 4, The constant "meta" should be renamed to UPPERCASE per repo convention; rename the declaration "meta" to "META" (and any other lowercase constant at the same file, e.g., the one noted around line 15) and update all local references and the export (e.g., export default META if applicable) so types (MetaRecord) remain unchanged and the identifier is consistent throughout the file.apps/website/content/roam/guides/exploring-discourse-graph/index.md-2-2 (1)
2-2:⚠️ Potential issue | 🟡 MinorUse sentence case in the frontmatter title.
Please adjust the title casing to align with docs copy standards.
✏️ Suggested change
-title: "Exploring Your Discourse Graph" +title: "Exploring your discourse graph"As per coding guidelines, "
apps/website/**/*.{md,mdx,js,ts,tsx,jsx}: Use sentence case for documentation copy by default."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/guides/exploring-discourse-graph/index.md` at line 2, The frontmatter title uses title case; update the frontmatter key `title` in the document (the existing string "Exploring Your Discourse Graph") to sentence case ("Exploring your discourse graph") so it follows the docs rule for sentence case in `title` values.apps/website/content/roam/use-cases/lab-notebooks.md-5-8 (1)
5-8:⚠️ Potential issue | 🟡 MinorAvoid publishing placeholder-only content.
This page is live (
published: true) but still contains only placeholder text. Consider keeping it unpublished until content is ready.✅ Minimal fix
-published: true +published: false🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/use-cases/lab-notebooks.md` around lines 5 - 8, The page currently has only placeholder text ("Description coming soon!") but is published ("published: true"); either replace the placeholder with the real content for the Roam lab notebook use-case or toggle the frontmatter to unpublish by changing the published flag to false so the incomplete page is not live; locate the frontmatter entry "published: true" and the placeholder body "Description coming soon!" in lab-notebooks.md and update accordingly.apps/website/content/obsidian/use-cases/reading-clubs.md-5-8 (1)
5-8:⚠️ Potential issue | 🟡 MinorConsider keeping this page unpublished until substantive content is added.
Right now it’s mostly placeholder text, so surfacing it as published can feel incomplete to users.
✅ Minimal fix
-published: true +published: false🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/obsidian/use-cases/reading-clubs.md` around lines 5 - 8, This page is currently marked published with only placeholder content; edit the frontmatter to unpublish it by changing the published: true flag to published: false (or remove the published key) in the reading-clubs.md frontmatter and optionally add a short TODO comment in the body (e.g., replace "Description coming soon!" with a brief note that the page is draft) so it won't appear live until substantive content is added.apps/website/content/roam/welcome/installation.md-8-8 (1)
8-8:⚠️ Potential issue | 🟡 MinorFix grammar: missing verb "is".
The sentence is missing the verb "is" before "available".
📝 Proposed fix
-The Discourse Graphs extension available for installation via Roam Depot. +The Discourse Graphs extension is available for installation via Roam Depot.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/welcome/installation.md` at line 8, The sentence "The Discourse Graphs extension available for installation via Roam Depot." is missing the verb "is"; update the sentence in installation.md (the line starting with "The Discourse Graphs extension available for installation via Roam Depot.") to read "The Discourse Graphs extension is available for installation via Roam Depot." so the sentence is grammatically correct.apps/website/content/roam/welcome/installation.md-8-10 (1)
8-10:⚠️ Potential issue | 🟡 MinorUse "Discourse Graph" (singular) for consistency with the official extension name.
Line 8 incorrectly uses "Discourse Graphs" (plural) while line 10 correctly uses "Discourse Graph" (singular). The official product name for the Roam extension is "Discourse Graph," as confirmed throughout the documentation and README. Change line 8 to: "The Discourse Graph extension available for installation via Roam Depot."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/welcome/installation.md` around lines 8 - 10, Replace the incorrect plural name "Discourse Graphs" with the official singular name "Discourse Graph" in the markdown content; locate the sentence that currently reads "The Discourse Graphs extension available for installation via Roam Depot." and update it to "The Discourse Graph extension available for installation via Roam Depot." ensuring consistency with the existing correct instance "Discourse Graph" used elsewhere in the file.apps/website/content/obsidian/fundamentals/base-grammar.md-10-21 (1)
10-21:⚠️ Potential issue | 🟡 MinorFix heading level progression (
###→##).Headings currently skip a level and trigger markdownlint
MD001.Proposed fix
-### Nodes +## Nodes ... -### Relations +## Relations🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/obsidian/fundamentals/base-grammar.md` around lines 10 - 21, Update the heading level progression by changing the "### Nodes" and "### Relations" headings to "## Nodes" and "## Relations" respectively so the document uses sequential heading levels (fixes markdownlint MD001); locate the headings labeled "Nodes" and "Relations" in the file and replace their triple-hash markers with double-hash markers.apps/website/content/obsidian/fundamentals/what-is-a-discourse-graph.md-12-16 (1)
12-16:⚠️ Potential issue | 🟡 MinorAdd alt text to both images.
Both image tags are missing alt text, which hurts accessibility and triggers
MD045.Proposed fix
- + ... - +🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/obsidian/fundamentals/what-is-a-discourse-graph.md` around lines 12 - 16, The two markdown image tags showing /docs/roam/argument-map.png and /docs/roam/bans-hate-speech.png are missing alt text (causing MD045); update the image markup in what-is-a-discourse-graph.md to include concise, descriptive alt attributes for both images (e.g., alt="Argument map illustrating conceptual building blocks" and alt="Diagram showing bans and hate-speech relationships") so each  becomes  ensuring accessibility and resolving the MD045 lint error.apps/website/content/roam/guides/exploring-discourse-graph/discourse-context-overlay.md-40-42 (1)
40-42:⚠️ Potential issue | 🟡 MinorConsider updating or removing the outdated demo notation.
The comment "(old video demo)" suggests the embedded video may be outdated. Consider either updating the video to reflect current UX or removing the comment if the video is still accurate.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/guides/exploring-discourse-graph/discourse-context-overlay.md` around lines 40 - 42, The comment "(old video demo)" above the Loom URL is potentially outdated; either replace the parenthetical note with an updated descriptor and/or a new demo URL reflecting current UX, or remove the "(old video demo)" text entirely if the linked video is still accurate—locate the exact line containing "(old video demo)" and the Loom link https://www.loom.com/share/b3d6094cd14a466081b8aa8495eb6542 in discourse-context-overlay.md and update or delete the annotation accordingly.apps/website/content/obsidian/core-features/discourse-context.md-23-27 (1)
23-27:⚠️ Potential issue | 🟡 MinorFix the orphaned list item.
Line 27 contains a numbered item "3." that appears disconnected from any list structure. This seems to be a formatting error or leftover from editing. Consider removing it or integrating it properly into the preceding content.
📝 Suggested fix
If the line is redundant (as it repeats information from line 25), remove it:
### Method 3: Using hotkeys You can configure a custom hotkey in the Obsidian settings to quickly toggle the discourse context view. - -3. Configure a custom hotkey in settings🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/obsidian/core-features/discourse-context.md` around lines 23 - 27, The numbered orphan "3. Configure a custom hotkey in settings" under the "### Method 3: Using hotkeys" section is a stray list item; remove that redundant line (or convert it into a proper list item under the hotkeys paragraph) so the "Method 3" subsection reads cleanly without the disconnected "3." entry.apps/website/content/obsidian/core-features/creating-discourse-nodes.md-31-31 (1)
31-31:⚠️ Potential issue | 🟡 MinorAdd alt text to images for accessibility.
Several images are missing alt text, which impacts accessibility and screen reader users.
Suggested fix
- +- +- +Also applies to: 43-43, 46-46
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/obsidian/core-features/creating-discourse-nodes.md` at line 31, The markdown image tags like "" are missing alt text; update each occurrence (the shown image with filename yYxtLKkx6B.png and the other images referenced at the same block) to use descriptive alt text by replacing "" with "" (e.g., describe the graph or UI shown) so screen readers can convey the image content.apps/website/content/roam/guides/sharing-discourse-graph.md-12-12 (1)
12-12:⚠️ Potential issue | 🟡 MinorAdd alt text to images for accessibility.
Suggested fix
- +- +- -  + - Also applies to: 22-22, 48-48
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/guides/sharing-discourse-graph.md` at line 12, Update the image markdown to include descriptive alt text for accessibility by replacing bare image tags like "" (and the similar occurrences at the other reported locations) with descriptive alt attributes such as ""; ensure each image line (the three bare  entries) gets an appropriate short descriptive alt string that conveys the image content.apps/website/content/obsidian/core-features/creating-discourse-nodes.md-42-42 (1)
42-42:⚠️ Potential issue | 🟡 MinorFix typo: "chosing" → "choosing".
-If a page is not a discourse node, you can turn it into one by clicking on the file menu, and chosing "Convert into" option +If a page is not a discourse node, you can turn it into one by clicking on the file menu, and choosing the "Convert into" option🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/obsidian/core-features/creating-discourse-nodes.md` at line 42, Fix the typo in the sentence that currently reads 'chosing'—change it to 'choosing' in the string "Convert into" option within the content of creating-discourse-nodes.md (the sentence starting "If a page is not a discourse node...").apps/website/content/roam/guides/creating-discourse-nodes.md-24-24 (1)
24-24:⚠️ Potential issue | 🟡 MinorAdd alt text to the image.
- +🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/guides/creating-discourse-nodes.md` at line 24, The image markdown currently has an empty alt attribute (); update that image tag to include descriptive alt text inside the brackets (e.g., [Roam node template screenshot]) so the line referencing /docs/roam/node-template.png provides accessible alternate text.apps/website/content/obsidian/core-features/creating-discourse-nodes.md-35-38 (1)
35-38:⚠️ Potential issue | 🟡 MinorFix broken markdown list structure.
The numbered list formatting is broken. Item "2." appears on the same line as the image, and "Alternatively, you can right-click..." is redundant given step 1 already says "Right-click."
### Using the right-click menu -1. Right-click on the selected text - Alternatively, you can right-click on the selected text - - 2. Choose a node type from the "Turn into discourse node" menu +1. Right-click on the selected text +  +2. Choose a node type from the "Turn into discourse node" menu🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/obsidian/core-features/creating-discourse-nodes.md` around lines 35 - 38, Remove the redundant "Alternatively, you can right-click on the selected text" phrase and fix the numbered list so each item is on its own line: keep "1. Right-click on the selected text" as the first list item, place the image markdown (alt "right click menu") on its own line immediately after item 1 (or as a block between items), and ensure "2. Choose a node type from the 'Turn into discourse node' menu" starts on a new line as item 2.apps/website/content/roam/fundamentals/relations-patterns.md-23-23 (1)
23-23:⚠️ Potential issue | 🟡 MinorAdd alt text to images for accessibility.
Static analysis correctly identifies missing alt text (MD045). Images should have descriptive alt text for accessibility.
Suggested fix for all images
- +- +- +🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/fundamentals/relations-patterns.md` at line 23, The image markdown "" is missing alt text; replace it with a descriptive alt attribute (for example: "") and do the same for any other occurrences of "" in this document to satisfy MD045 accessibility checks.apps/website/content/roam/guides/querying-discourse-graph.md-16-30 (1)
16-30:⚠️ Potential issue | 🟡 MinorAdd alt text to images for accessibility.
Multiple images lack alt text, which is flagged by static analysis (MD045). Alt text improves accessibility for screen readers and provides context when images fail to load.
Suggested fix for a few examples
- + - + - + - +The same pattern should be applied to remaining images at lines 38, 44, 52, 58, and 64.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/guides/querying-discourse-graph.md` around lines 16 - 30, Several images in the markdown use bare image syntax like "" without alt text (triggers MD045); update each image tag to include descriptive alt text (e.g., replace "" with "") and do the same for the other image filenames shown in the diff ("/docs/roam/query-drawer.png", "/docs/roam/query-drawer-informs.png", "/docs/roam/query-drawer-supports.png" and the remaining images referenced at the noted lines) so each image has meaningful alt text for accessibility.apps/website/content/roam/guides/exploring-discourse-graph/discourse-attributes.md-19-19 (1)
19-19:⚠️ Potential issue | 🟡 MinorAdd alt text to the image for accessibility.
The image is missing alternative text, which is required for screen readers and accessibility compliance.
Proposed fix
- +🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/guides/exploring-discourse-graph/discourse-attributes.md` at line 19, The image markdown line currently has an empty alt text (""); update that markdown to include a meaningful alt string describing the image (e.g., "Settings screen showing discourse attributes") by replacing the empty brackets with the chosen description so the line becomes like "[Alt text](/docs/roam/settings-discourse-attributes.png)"; ensure the alt text succinctly conveys the image content for screen readers and accessibility.apps/website/content/roam/guides/exploring-discourse-graph/discourse-attributes.md-31-31 (1)
31-31:⚠️ Potential issue | 🟡 MinorExpand abbreviation for clarity.
"Atm" is informal and may be unclear to some readers. Use "Currently" or "At the moment" instead.
Proposed fix
-- `count` is the operation. Atm, this is the only supported operation for basic discourse functions. +- `count` is the operation. Currently, this is the only supported operation for basic discourse functions.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/guides/exploring-discourse-graph/discourse-attributes.md` at line 31, Replace the informal abbreviation "Atm" in the sentence that starts with "`count` is the operation." with a clear phrasing such as "At the moment" or "Currently" so the sentence reads: "`count` is the operation. At the moment, this is the only supported operation for basic discourse functions..." (reference the line containing "`count` is the operation." to locate the text to change).apps/website/content/obsidian/advanced-features/sync-and-import.md-10-12 (1)
10-12:⚠️ Potential issue | 🟡 MinorRemove the blank separator between these blockquotes.
Line 11 trips
MD028(no-blanks-blockquote), so this page will keep a markdownlint warning until the separator is removed or kept inside the quote.Suggested fix
> **Note:** This feature is currently in **beta**. The sync functionality requires an active connection to the Discourse Graph database. - > **Warning:** When using sync and import:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/obsidian/advanced-features/sync-and-import.md` around lines 10 - 12, Remove the blank line separating the two blockquote lines so they are consecutive blockquote paragraphs; specifically, delete the empty line between the lines that start with "**Note:** This feature is currently in **beta**..." and "**Warning:** When using sync and import:" to satisfy MD028 (no-blanks-blockquote).apps/website/content/obsidian/core-features/canvas.md-89-149 (1)
89-149:⚠️ Potential issue | 🟡 MinorSwitch the generic section headings to sentence case.
This section still uses title case for generic headings like
Canvas Features,Export Options,Common Issues, andGetting Help. Please normalize those, and clean up the nearby copy nits (SVG/PNG,up-to-date) while you're here.As per coding guidelines,
apps/website/**/*.{md,mdx,js,ts,tsx,jsx}: Use sentence case for documentation copy by default.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/obsidian/core-features/canvas.md` around lines 89 - 149, Change the generic section headings from title case to sentence case (e.g., "Canvas Features" -> "Canvas features", "Export Options" -> "Export options", "Common Issues" -> "Common issues", "Getting Help" -> "Getting help") and update nearby copy nits: use "SVG export" and "PNG export" (instead of "SVG Export"/"PNG Export") and change "up-to-date" to "up to date" in the troubleshooting list; keep other content unchanged.
🧹 Nitpick comments (24)
apps/website/app/components/Logo.tsx (2)
19-22: Add explicit return type for the component.Per coding guidelines, TypeScript functions should have explicit return types.
Suggested fix
export const Logo = ({ linked = true, textClassName = "text-neutral-dark", -}: LogoProps) => { +}: LogoProps): React.ReactElement => {🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/app/components/Logo.tsx` around lines 19 - 22, The Logo component lacks an explicit TypeScript return type; update the Logo function signature to declare its return type (e.g., React.ReactElement or JSX.Element) so it explicitly types the component's output; modify the exported Logo declaration that currently accepts (linked, textClassName) and uses LogoProps to include the appropriate return type annotation referencing the Logo component and LogoProps.
29-54: Consider extracting mask styles to a CSS class or using Tailwind's arbitrary properties.The inline styles for CSS mask properties require multiple ESLint disables. While necessary because Tailwind doesn't have built-in mask utilities, this could be cleaner with a CSS class in your stylesheet or using Tailwind's
[mask-image:url(...)]arbitrary property syntax (though browser prefix handling would still need consideration).This is a low-priority refactor since the current approach works correctly.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/app/components/Logo.tsx` around lines 29 - 54, The inline mask styles on the brand JSX (the fragment assigned to brand) should be moved out of inline style to avoid multiple ESLint disables: create a dedicated CSS class (e.g., .logo-mask) or use Tailwind arbitrary utilities (e.g., [mask-image:url('/logo-light-48.svg')] plus other arbitrary mask properties) and include the -webkit- prefixed rules in that CSS class to ensure cross-browser support; then replace the style prop on the span with the new className (and remove the eslint-disable comments) so the mask rules live in CSS rather than inline styles in the Logo component.apps/website/app/(docs)/layout.tsx (1)
19-21: Add explicit return type for the layout component.Per coding guidelines, functions in TypeScript should have explicit return types.
Suggested fix
-const DocsLayout = ({ children }: { children: React.ReactNode }) => { +const DocsLayout = ({ children }: { children: React.ReactNode }): React.ReactElement => { return <div className={`${inter.variable} antialiased`}>{children}</div>; };🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/app/`(docs)/layout.tsx around lines 19 - 21, DocsLayout is missing an explicit TypeScript return type; update the component signature to declare its return type (e.g., React.ReactElement or React.ReactNode) so the function has an explicit type. Locate the DocsLayout function and change its declaration to include the return type for the function (referencing DocsLayout, the children prop and use of inter.variable) so the signature reads with an explicit return type rather than relying on inference. Ensure imports already include React types if needed.apps/website/content/roam/guides/extending-personalizing-graph.md (1)
34-34: Add trailing newline at end of file.The file should end with a newline character for consistency with POSIX standards and to avoid diff noise in future edits.
Suggested fix
If you want to explore or understand that legacy workflow, it will be useful to [learn more about the extension grammar](/docs/roam/fundamentals/grammar). +🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/guides/extending-personalizing-graph.md` at line 34, Add a single trailing newline character to the end of the file to satisfy POSIX newline conventions and avoid future diff noise; open the file containing the line "If you want to explore or understand that legacy workflow, it will be useful to [learn more about the extension grammar](/docs/roam/fundamentals/grammar)." and ensure there is exactly one newline character after the final line (i.e., the file ends with '\n').apps/website/content/roam/fundamentals/what-is-a-discourse-graph.md (1)
20-20: Add trailing newline at end of file.The file should end with a newline character.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/fundamentals/what-is-a-discourse-graph.md` at line 20, Add a trailing newline character to the end of the Markdown file so the last line ("Discourse Graphs are not a new idea...") is terminated with a newline; open the file apps/website/content/roam/fundamentals/what-is-a-discourse-graph.md and ensure the final line ends with '\n' (save file with a newline at EOF).apps/website/app/(home)/page.tsx (1)
405-407: Consolidate duplicated hard-nav docs links.Both sections repeat the same comment + lint suppression + anchor pattern. Consider extracting a tiny helper/component (e.g.,
HardDocsLink) to keep this logic centralized.Also applies to: 423-425
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/app/`(home)/page.tsx around lines 405 - 407, Create a small React component (e.g., HardDocsLink) that renders the hard navigation anchor for the Nextra docs and centralizes the comment and eslint-disable-next-line suppression instead of duplicating the pattern around <a href="/docs/roam/">Documentation</a>; replace both occurrences with <HardDocsLink /> (or an imported named component) so the anchor, the explanatory comment, and the eslint suppression live in one place (ensure the component returns the same <a href="/docs/roam/">Documentation</a> markup and is used where the duplicated blocks currently appear).apps/website/next.config.ts (1)
17-19: Add an explicit return type onredirectsfor TypeScript clarity.This keeps config typing strict and self-documenting.
♻️ Suggested change
- async redirects() { - return DOCS_REDIRECTS; - }, + redirects: async (): Promise<import("next").Redirect[]> => { + return DOCS_REDIRECTS; + },As per coding guidelines, "
**/*.{ts,tsx}: Use explicit return types for functions in TypeScript".🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/next.config.ts` around lines 17 - 19, The async redirects function lacks an explicit TypeScript return type; update the signature of redirects to return Promise<import('next').Redirect[]> (or the appropriate Next.js Redirect[] type) and ensure DOCS_REDIRECTS is typed or cast to that same type so the function's return is fully typed and compatible with Next.js expectations.apps/website/content/obsidian/advanced-features/command-palette.md (1)
2-2: Capitalize "Command Palette" in title to match the official Obsidian feature name.The frontmatter title uses "Command palette integration" with lowercase 'p', but throughout the document (lines 8, 10, 16, 18) you correctly capitalize it as "Command Palette". The title should match the official UI feature name for consistency. As per coding guidelines, official UI labels should be capitalized.
📝 Proposed fix
-title: "Command palette integration" +title: "Command Palette integration"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/obsidian/advanced-features/command-palette.md` at line 2, Frontmatter title uses "Command palette integration" with a lowercase 'p'; update the frontmatter title field to "Command Palette integration" so it matches the official UI label used elsewhere in the doc. Edit the title property in the markdown frontmatter (the title field) to capitalize "Palette" exactly as "Command Palette" to ensure consistency with other occurrences in the document.apps/website/content/roam/use-cases/enhanced-zettelkasten.md (1)
8-8: Capitalize "Zettelkasten" as a proper methodology name."Zettelkasten" is a proper noun referring to a specific note-taking methodology and should be capitalized.
📝 Proposed fix
-Maarten Van Doorn has integrated the discourse graph into his take on applying the zettelkasten to his research. +Maarten Van Doorn has integrated the discourse graph into his take on applying the Zettelkasten to his research.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/use-cases/enhanced-zettelkasten.md` at line 8, In the sentence currently reading "Maarten Van Doorn has integrated the discourse graph into his take on applying the zettelkasten to his research." capitalize the methodology name by replacing "zettelkasten" with "Zettelkasten" so the line reads "...applying the Zettelkasten to his research."; update the exact markdown content string to use the capitalized form.apps/website/content/roam/welcome/getting-started.md (1)
16-16: Adjust these headings to sentence case.Both headings use title-case words after the colon; switch to sentence case to match repo docs style.
As per coding guidelines `apps/website/**/*.{md,mdx,js,ts,tsx,jsx}`: “Use sentence case for documentation copy by default.”Proposed fix
-## Guides: Jump right in +## Guides: jump right in ... -## Fundamentals: Dive a little deeper +## Fundamentals: dive a little deeperAlso applies to: 26-26
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/welcome/getting-started.md` at line 16, Change the heading "## Guides: Jump right in" to sentence case by lowercasing the first word after the colon (i.e., "## Guides: jump right in"); do the same for the other matching heading referenced in the comment (line 26) so both headings follow the repo docs rule to use sentence case in apps/website content files.apps/website/content/roam/guides/tagging-candidate-nodes.md (1)
35-35: Address the TODO comment.The TODO indicates that the demonstration GIF needs updating for smoother UX. Consider tracking this content improvement.
Would you like me to open an issue to track updating this demonstration GIF with the improved UX flow (including auto-remove tag)?
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/guides/tagging-candidate-nodes.md` at line 35, The content contains a TODO HTML comment "<!-- TODO: update this gif with smoother UX, including auto-remove tag -->" indicating the demonstration GIF is outdated; replace the current GIF in the roam/guides/tagging-candidate-nodes.md content with a new, smoother recording that demonstrates the auto-remove tag behavior, update the image filename and alt text/caption to reflect the new behavior, remove the TODO comment, and optionally create a tracking issue describing the required UX improvements if you prefer to stage the change rather than commit the new asset immediately.apps/website/content/roam/guides/sharing-discourse-graph.md (1)
2-2: Use sentence case for the title.Per coding guidelines, documentation titles should use sentence case.
-title: "Sharing Your Discourse Graph" +title: "Sharing your discourse graph"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/guides/sharing-discourse-graph.md` at line 2, The frontmatter title "Sharing Your Discourse Graph" uses Title Case; update the title value in the file's frontmatter to sentence case (e.g., "Sharing your discourse graph") so it follows the documentation guideline; edit the title string in the same frontmatter entry to the corrected sentence-case form.apps/website/content/roam/guides/creating-discourse-nodes.md (1)
20-20: Format demo URL as a clickable link.The bare URL won't render as a clickable link in all Markdown renderers. Consider formatting it consistently with the other docs.
-https://www.loom.com/share/471fcf7dc13246439cb35feedb110470 +[https://www.loom.com/share/471fcf7dc13246439cb35feedb110470](https://www.loom.com/share/471fcf7dc13246439cb35feedb110470)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/guides/creating-discourse-nodes.md` at line 20, Replace the bare Loom URL with a Markdown-formatted clickable link in creating-discourse-nodes.md by wrapping the URL with link text (e.g., [Demo video](https://www.loom.com/share/471fcf7dc13246439cb35feedb110470)) so it renders consistently like other docs; update the line containing the raw URL to use that bracketed link form.apps/website/app/(nextra)/nextra-css.css (1)
7-17: Consider using CSS variables or Tailwind colors for consistency.The hardcoded
#1f1f1fcolor works, but using a Tailwind color (e.g.,theme('colors.gray.900')) or CSS variable could improve maintainability if the color palette changes.That said, the
!importantoverrides are justified here to ensure Nextra's built-in search styles are properly overridden in light mode.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/app/`(nextra)/nextra-css.css around lines 7 - 17, Replace the hardcoded `#1f1f1f` with a maintainable CSS variable and use that variable in the selectors (html:not(.dark) .nextra-search-results a, html:not(.dark) .nextra-search-results a[data-focus], html:not(.dark) .nextra-search-results mark); add a root-level variable (e.g., --nextra-search-text) and reference var(--nextra-search-text) in those rules so the color can be changed centrally (keep the existing !important overrides).apps/website/content/obsidian/configuration/node-types-templates.md (1)
52-52: Self-referencing link may be a placeholder.This link points to the "Working with templates" section on the same page, but is labeled "Explore advanced template usage." Either update the link to point to actual advanced content, or remove it if it's redundant.
-- [Explore advanced template usage](/docs/obsidian/configuration/node-types-templates#working-with-templates) +- [Working with templates](`#working-with-templates`)Or remove the link if the section above already covers this.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/obsidian/configuration/node-types-templates.md` at line 52, The markdown contains a self-referencing link with link text "Explore advanced template usage" pointing to the anchor "#working-with-templates" which appears redundant or a placeholder; either replace the link target with the correct advanced content anchor or external URL, or remove the entire link (the line "- [Explore advanced template usage](/docs/obsidian/configuration/node-types-templates#working-with-templates)") so the section isn’t self-referential—ensure any replacement anchor actually exists in the document and that the link text matches the destination.apps/website/content/roam/guides/querying-discourse-graph.md (1)
1-6: Title should use sentence case.The title "Querying Your Discourse Graph" uses title case. As per coding guidelines, documentation copy should use sentence case by default.
Suggested fix
--- -title: "Querying Your Discourse Graph" +title: "Querying your discourse graph" date: "2025-01-01" author: "" published: true ---🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/guides/querying-discourse-graph.md` around lines 1 - 6, Update the frontmatter title value from title case to sentence case by changing the YAML key "title" in the document's frontmatter (the line starting with title:) from "Querying Your Discourse Graph" to "Querying your discourse graph" so the documentation copy follows the sentence-case guideline.apps/website/content/roam/fundamentals/grammar/operators-relations.md (1)
48-52: Minor formatting inconsistency.Line 51 uses
**source:**(colon inside bold) while all other field labels use**source**:(colon outside bold). Consider aligning for consistency.Suggested fix
### `with text` - **description**: node content contains some text -- **source:** a `page`, `block`, or `discourse node` +- **source**: a `page`, `block`, or `discourse node` - **target**: a `string` that specifies the target text to find in the node content🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/fundamentals/grammar/operators-relations.md` around lines 48 - 52, In the "### `with text`" block, change the label formatting from `**source:**` to match the other fields by moving the colon outside the bold (i.e., `**source**:`); ensure `**description**:` and `**target**:` remain unchanged so all field labels use the same bolded-label-then-colon style.apps/website/content/obsidian/core-features/creating-discourse-relationships.md (1)
14-17: Capitalize UI element names consistently."Command Palette" is an official Obsidian UI element and should be capitalized. As per coding guidelines, exact UI labels should be capitalized.
Suggested fix
Alternatively, you can: - Set a hotkey to toggle the discourse context view - - Access it via the Command Palette + - Access it via the **Command Palette** 🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/obsidian/core-features/creating-discourse-relationships.md` around lines 14 - 17, The text uses inconsistent capitalization for UI labels: change the list item "Access it via the Command Palette" to use the exact UI label "Command Palette" (capitalized) to match Obsidian UI conventions; locate the bullet "- Access it via the Command Palette" (and any other occurrences of "command palette" or UI element names in this file) and update them to the properly capitalized form.apps/website/app/(docs)/docs/_components/DocsPageTemplate.tsx (1)
8-9: Minor regex simplification opportunity.The regex
/(^|\n)#\s+\S/muses both the(^|\n)alternation and them(multiline) flag. With themflag,^already matches at line starts, making(^|\n)redundant.Simplified regex
const hasPrimaryHeading = (sourceCode: string): boolean => - /(^|\n)#\s+\S/m.test(sourceCode); + /^#\s+\S/m.test(sourceCode);🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/app/`(docs)/docs/_components/DocsPageTemplate.tsx around lines 8 - 9, The regex in hasPrimaryHeading uses a redundant ( ^|\n ) alternation alongside the m flag; simplify it by replacing /(^|\n)#\s+\S/m with a multiline-aware pattern /^#\s+\S/m in the hasPrimaryHeading function so ^ alone matches line starts and preserves the original behavior.apps/website/docsRouteMap.ts (1)
58-74: Add explicit return types and use helper consistently.Per coding guidelines, functions should have explicit return types. Also,
buildPlatformRedirectscreates redirect objects inline instead of using thecreateRedirecthelper.Proposed fix
-const createRedirect = (source: string, destination: string): Redirect => ({ +const createRedirect = (source: string, destination: string): Redirect => ({ source, destination, permanent: true, }); const buildPlatformRedirects = ( platform: "roam" | "obsidian", sections: Record<string, readonly string[]>, -): Redirect[] => +): Redirect[] => Object.entries(sections).flatMap(([section, slugs]) => - slugs.map((slug) => ({ - source: `/docs/${platform}/${slug}`, - destination: `/docs/${platform}/${section}/${slug}`, - permanent: true, - })), + slugs.map((slug) => + createRedirect( + `/docs/${platform}/${slug}`, + `/docs/${platform}/${section}/${slug}`, + ), + ), );As per coding guidelines: "Use explicit return types for functions in TypeScript."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/docsRouteMap.ts` around lines 58 - 74, Add explicit return types to both createRedirect and buildPlatformRedirects (e.g., createRedirect: (source: string, destination: string) => Redirect and buildPlatformRedirects: (platform: "roam" | "obsidian", sections: Record<string, readonly string[]>) => Redirect[]), and change buildPlatformRedirects to call the createRedirect helper for each redirect instead of constructing objects inline (replace the inline { source, destination, permanent: true } with createRedirect(source, destination)). Ensure the helper is used consistently and types align with the Redirect type.apps/website/content/roam/guides/exploring-discourse-graph/discourse-attributes.md (1)
13-13: Use sentence case for headings.Per coding guidelines, documentation should use sentence case by default. This heading and others (lines 25, 47) use title case instead.
Proposed fix for headings
-## Define Discourse Attributes +## Define discourse attributesAlso apply to:
- Line 25:
## Basic Discourse Relation Functions→## Basic discourse relation functions- Line 47:
## Compound Discourse Functions→## Compound discourse functionsAs per coding guidelines: "Use sentence case for documentation copy by default."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/roam/guides/exploring-discourse-graph/discourse-attributes.md` at line 13, Heading text uses title case; update the three headings to sentence case: change "## Define Discourse Attributes" to "## Define discourse attributes", "## Basic Discourse Relation Functions" to "## Basic discourse relation functions", and "## Compound Discourse Functions" to "## Compound discourse functions" so documentation follows the sentence-case guideline.apps/website/app/(docs)/docs/(landing)/page.tsx (1)
13-28: Consider adding explicit typing for the destinations array.The
as constassertion provides type narrowing, but an explicit type annotation would improve maintainability and catch mismatches with thePlatformBadgecomponent's expectedplatformprop values.Optional: Add explicit type
+type DocsDestination = { + description: string; + href: string; + platform: "roam" | "obsidian"; + title: string; +}; + -const DOCS_DESTINATIONS = [ +const DOCS_DESTINATIONS: readonly DocsDestination[] = [ { description: "Installation, graph building, querying, and advanced workflows for the Roam Research plugin.", href: "/docs/roam", platform: "roam", title: "Roam docs", }, // ... -] as const; +];🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/app/`(docs)/docs/(landing)/page.tsx around lines 13 - 28, Add an explicit type for the DOCS_DESTINATIONS array so its shape and the platform field align with the PlatformBadge component's expected platform union; define a DocsDestination type/interface (with title, description, href, platform) or reuse the existing PlatformBadge platform type, and annotate DOCS_DESTINATIONS: DocsDestination[] (or readonly DocsDestination[] if immutability is desired) to replace the sole use of as const—update any imports to reference the platform union type used by PlatformBadge to ensure compile-time safety.apps/website/content/obsidian/advanced-features/sync-and-import.md (1)
49-67: Use one name for the shared publishing target.This page alternates between
group,group space,lab space, and plainspace. Outside exact command labels, please pick one term and keep it consistent so readers don't assume these are different destinations.Also applies to: 83-107, 129-144
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/content/obsidian/advanced-features/sync-and-import.md` around lines 49 - 67, The content uses multiple names for the same publishing destination ("group", "group space", "lab space", "space"); pick one consistent term (e.g., "group space") for all descriptive text while preserving exact command labels like "Discourse Graph: Publish current node to lab space" as-is, then update all occurrences of the other variants across the document (including the sections around the publish steps and the other noted areas) so readers see a single, consistent destination name throughout.apps/website/app/(docs)/docs/obsidian/[[...mdxPath]]/page.tsx (1)
14-67: Extract the shared platform docs route helper.This file is now almost identical to
apps/website/app/(docs)/docs/roam/[[...mdxPath]]/page.tsxexcept for the platform slug and fallback title. A small helper/factory for the static params, loader, and metadata path would reduce drift the next time this route logic changes.As per coding guidelines,
**/*.{ts,tsx,js,jsx}: Prefer util functions for reusable logic and common operations.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/website/app/`(docs)/docs/obsidian/[[...mdxPath]]/page.tsx around lines 14 - 67, This route duplicates logic from the Roam docs page; extract a reusable helper/factory that takes the platform slug ("obsidian") and the fallback title and returns the generateStaticParams, loader (loadPage/importPage wrapper), and generateMetadata logic to avoid drift. Create a util (e.g., createPlatformDocsRoute(platformSlug, fallbackTitle)) that uses generateStaticParamsFor, importPage, and exposes generateStaticParams, loadPage, Page wrapper, and generateMetadata signatures used here, then replace the local generateAllStaticParams/generateStaticParams/loadPage/generateMetadata implementations in this file with calls to that helper (passing "obsidian" and "Obsidian docs" as needed) so the Roam route can reuse the same factory with its slug and title.
| const Page = async ({ params }: DocsPageProps): Promise<React.ReactElement> => { | ||
| try { | ||
| const { mdxPath } = await params; | ||
| const result = await loadPage(mdxPath); | ||
| const { default: MDXContent, ...wrapperProps } = result; | ||
|
|
||
| return ( | ||
| <DocsPageTemplate {...wrapperProps}> | ||
| <MDXContent params={{ mdxPath: mdxPath ?? [] }} /> | ||
| </DocsPageTemplate> | ||
| ); | ||
| } catch (error) { | ||
| console.error("Error rendering Roam docs page:", error); | ||
| notFound(); | ||
| } |
There was a problem hiding this comment.
Don’t turn every docs failure into a 404.
These catch blocks map any load/render/metadata exception to notFound() or generic metadata. During static generation, that means a broken MDX module can quietly become a 404 page instead of failing the build. Please only convert confirmed missing-page cases to notFound() and let unexpected errors surface.
Also applies to: 52-66
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/website/app/`(docs)/docs/roam/[[...mdxPath]]/page.tsx around lines 35 -
49, The catch in Page currently converts any error from loadPage/MDX rendering
into notFound(); instead, update the error handling in Page (and the similar
metadata block) to only call notFound() when the error clearly indicates a
missing page (e.g., a deterministic "module not found"/not-found sentinel
returned by loadPage), and rethrow or propagate all other errors so builds fail
visibly; specifically, inspect the thrown error from loadPage in Page and only
call notFound() for the explicit missing-page condition, otherwise throw the
error.
| published: true | ||
| --- | ||
|
|
||
| Description coming soon! |
There was a problem hiding this comment.
Avoid publishing this page before content migration is complete.
Line [5] publishes the page, but Line [8] is still placeholder-only content.
Suggested minimal fix
-published: true
+published: false📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| published: true | |
| --- | |
| Description coming soon! | |
| published: false | |
| --- | |
| Description coming soon! |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/website/content/obsidian/use-cases/lab-notebooks.md` around lines 5 - 8,
The page is marked published while it contains only placeholder text
("Description coming soon!"); change the frontmatter key published from true to
false (or remove it) so the page is not publicly published until real content
replaces the placeholder, and ensure the placeholder line is updated or removed
before re-enabling published: true.
| published: true | ||
| --- | ||
|
|
||
| Description coming soon! |
There was a problem hiding this comment.
Do not publish placeholder-only docs pages.
Line [5] sets this page live, but Line [8] is still placeholder text. Please either migrate real content now or keep it unpublished until content is ready.
Suggested minimal fix
-published: true
+published: false📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| published: true | |
| --- | |
| Description coming soon! | |
| published: false | |
| --- | |
| Description coming soon! |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/website/content/obsidian/use-cases/research-roadmapping.md` around lines
5 - 8, The page is marked published but contains only placeholder text; either
set the frontmatter key "published" to false or replace the placeholder
"Description coming soon!" with real content before leaving the page published.
Locate the frontmatter "published: true" and change it to "published: false" if
you aren't adding content now, or update the body by replacing the placeholder
text with the actual page content so the live page is not a stub.
|
|
||
| The overlay is an optional feature that is turned off by default. To turn it on, go to the grammar tab in the config page and check the box for overlay. | ||
|
|
||
|  |
There was a problem hiding this comment.
Add alt text for accessibility.
The screenshot is missing alternative text. Based on the context (showing the overlay enable checkbox in settings), provide descriptive alt text.
♿ Proposed fix
-
+📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
|  | |
|  |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@apps/website/content/roam/guides/exploring-discourse-graph/discourse-context-overlay.md`
at line 20, The image tag currently lacks alt text; update the markdown image
 to include a descriptive
alt string such as "Settings modal showing the Discourse Context Overlay with
the 'Enable overlay' checkbox toggled on" so screen readers convey that this
screenshot displays the overlay enable checkbox in settings (replace the empty
brackets in the existing image reference).
|
|
||
| The popover is simple to operate. Simply click on the icon to bring up the [discourse context](/docs/roam/guides/exploring-discourse-graph/discourse-context) component in-line for quick reference. | ||
|
|
||
|  |
There was a problem hiding this comment.
Add alt text for accessibility.
The image is missing alternative text. Based on the "Popover" section context, provide descriptive alt text.
♿ Proposed fix
-
+📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
|  | |
|  |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@apps/website/content/roam/guides/exploring-discourse-graph/discourse-context-overlay.md`
at line 26, The image tag '' lacks
alt text; update it to include a concise, descriptive alt string that reflects
the Popover context (e.g., "Popover showing discourse context overlay with
highlighted nodes and metadata"), replacing the empty brackets so the markdown
becomes '' to improve
accessibility.
|
|
||
| ## Group by target node | ||
|
|
||
|  |
There was a problem hiding this comment.
Add alt text for accessibility.
The image is missing alternative text, which is essential for screen reader users and accessibility compliance. Based on the context ("Group by target node" section), provide descriptive alt text.
♿ Proposed fix
-
+🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@apps/website/content/roam/guides/exploring-discourse-graph/discourse-context.md`
at line 17, The image markdown
"" lacks alt text; update
that markdown to include a concise, descriptive alt attribute like "GIF showing
grouping discourse graph by target node: nodes clustered around a selected
target with edges highlighting incoming relationships" so screen readers get
context and it matches the "Group by target node" section.
|
|
||
| ## Filter results | ||
|
|
||
|  |
There was a problem hiding this comment.
Add alt text for accessibility.
The image is missing alternative text. Based on the section heading ("Filter results"), provide descriptive alt text for screen readers.
♿ Proposed fix
-
+📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
|  | |
|  |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@apps/website/content/roam/guides/exploring-discourse-graph/discourse-context.md`
at line 21, The image markdown line
'' lacks alt text; update that image
tag to include a concise descriptive alt string reflecting the "Filter results"
section (e.g., "Animated GIF showing applying filters to discourse graph
results, narrowing nodes and highlighting matches") so screen readers can convey
the image purpose; ensure you only change the contents between the square
brackets for the alt text and keep the existing image path intact.
|
|
||
| The extension has node settings tabs for each node you define, which provides a query over all of your nodes of that type. For example, you can go to the Claim tab to see all the Claim nodes in your graph. | ||
|
|
||
|  |
There was a problem hiding this comment.
Add alt text for accessibility.
The screenshot is missing alternative text. Based on the context (node index settings tab), provide descriptive alt text.
♿ Proposed fix
-
+🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 15-15: Images should have alternate text (alt text)
(MD045, no-alt-text)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/website/content/roam/guides/exploring-discourse-graph/node-index.md` at
line 15, The markdown image tag "" is
missing alt text — update that tag in node-index.md to include a concise,
descriptive alt string (e.g., "Node index settings tab in Roam: toggles and
options for controlling node indexing and display") so the screenshot is
accessible to screen readers by replacing the empty brackets with the chosen alt
text.
|  | ||
|  | ||
|  |
There was a problem hiding this comment.
Add descriptive alt text to images for accessibility.
All three images are missing alt text, which is required for screen readers and accessibility compliance (WCAG 2.1 Level A).
♿ Proposed fix with descriptive alt text
-
-
-
+
+
+📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
|  | |
|  | |
|  | |
|  | |
|  | |
|  |
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 12-12: Images should have alternate text (alt text)
(MD045, no-alt-text)
[warning] 13-13: Images should have alternate text (alt text)
(MD045, no-alt-text)
[warning] 14-14: Images should have alternate text (alt text)
(MD045, no-alt-text)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/website/content/roam/welcome/installation.md` around lines 12 - 14,
Three images in installation.md lack alt text which breaks accessibility; update
the three markdown image tags referencing /docs/roam/browse-roam-depot.png,
/docs/roam/find-in-roam-depot.png, and
/docs/roam/install-instruction-roam-depot.png to include concise, descriptive
alt text (e.g., "Browse Roam Depot showing search results", "Find button in Roam
Depot interface", "Installation instructions modal in Roam Depot") by changing
each  to  so screen readers convey the image
purpose.
| const collectDocRecords = async () => { | ||
| const docFiles = await Promise.all( | ||
| DOC_DIRECTORIES.map((directory) => | ||
| collectMarkdownFiles(path.join(CONTENT_ROOT, directory)), | ||
| ), | ||
| ); | ||
| const allFiles = docFiles.flat(); | ||
| const records = await Promise.all(allFiles.map(readDocRecord)); |
There was a problem hiding this comment.
Index content/ itself, not only the platform subfolders.
routePathFromContentFile() already has logic for root-level docs like content/index.mdx, but collectDocRecords() only walks content/roam and content/obsidian. As written, /docs and any future shared docs pages under content/ never make it into Pagefind.
Suggested fix
const collectDocRecords = async () => {
- const docFiles = await Promise.all(
- DOC_DIRECTORIES.map((directory) =>
- collectMarkdownFiles(path.join(CONTENT_ROOT, directory)),
- ),
- );
- const allFiles = docFiles.flat();
+ const allFiles = await collectMarkdownFiles(CONTENT_ROOT);
const records = await Promise.all(allFiles.map(readDocRecord));
return records.filter((record) => record !== null);
};📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| const collectDocRecords = async () => { | |
| const docFiles = await Promise.all( | |
| DOC_DIRECTORIES.map((directory) => | |
| collectMarkdownFiles(path.join(CONTENT_ROOT, directory)), | |
| ), | |
| ); | |
| const allFiles = docFiles.flat(); | |
| const records = await Promise.all(allFiles.map(readDocRecord)); | |
| const collectDocRecords = async () => { | |
| const allFiles = await collectMarkdownFiles(CONTENT_ROOT); | |
| const records = await Promise.all(allFiles.map(readDocRecord)); | |
| return records.filter((record) => record !== null); | |
| }; |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/website/scripts/build-docs-search-index.mjs` around lines 173 - 180,
collectDocRecords only collects markdown from subfolders listed in
DOC_DIRECTORIES, so root-level files under CONTENT_ROOT (e.g.,
content/index.mdx) are omitted; update collectDocRecords to also include files
directly under CONTENT_ROOT by adding CONTENT_ROOT itself to the directories to
scan or separately calling collectMarkdownFiles(CONTENT_ROOT) so readDocRecord
and routePathFromContentFile receive root-level files too, ensuring Pagefind
indexes /docs and shared docs pages.
1 participant
Summary by CodeRabbit
New Features